</> 技術筆記Tech Notes

DXCore API： 日期工具

· 軟體專案/DXCore - JavaScript 程式庫 javascript

一、概述

日期工具類別提供了一系列與日期時間相關的實用功能，讓您能夠輕鬆地進行日期的格式化、運算、比較和解析。

使用範例：

// 建立日期工具的實例
const 工具 = new 日期工具();

// 使用格式化方法
const 格式化日期 = 工具.格式化(new Date(), 'YYYY-MM-DD');
console.log(格式化日期); // 輸出形如 "2023-11-15" 的日期字串

二、屬性

Units

一個物件，定義了可用於日期運算的時間單位。

  • Year: ‘year’

  • Month: ‘month’

  • Day: ‘day’

  • Hour: ‘hour’

  • Minute: ‘minute’

  • Second: ‘second’

  • Millisecond: ‘millisecond’

UnitNames

一個陣列，包含了所有 Units 物件中定義的時間單位名稱。

[‘year’, ‘month’, ‘day’, ‘hour’, ‘minute’, ‘second’, ‘millisecond’]

三、方法

加上(date, unit, count)

為指定的日期新增指定數量的時間單位，並返回更新後的新日期。

  • 參數:

    • date (Date): 要處理的日期物件。

    • unit (string): 要新增的時間單位類型。支援的值包括：‘year’, ‘month’, ‘day’。

    • count (number): 要新增的時間單位數量（可為正或負數）。

  • 返回: Date - 新增時間單位後的 Date 物件。

  • 拋出錯誤:

    • Error: 當傳入無效的 unit 時（非 ‘year’, ‘month’, ‘day’）。

  • 範例:

    const 工具 = new 日期工具();
const date = new Date('2023-11-01');

// 新增 5 天
const newDate1 = 工具.加上(date, 'day', 5);
console.log(newDate1); // 2023-11-06

// 新增 2 個月
const newDate2 = 工具.加上(date, 'month', 2);
console.log(newDate2); // 2024-01-01

// 減少 1 年
const newDate3 = 工具.加上(date, 'year', -1);
console.log(newDate3); // 2022-11-01

減去(日期, 單位, 數量)

從指定的日期中減去指定的單位數量，並返回新的日期物件。

  • 參數:

    • 日期 (Date): 要操作的原始 Date 物件。

    • 單位 (string): 要減去的日期和時間單位 (參考 Units 屬性)。

    • 數量 (number): 要減去的單位數量。

  • 返回: Date - 減去指定單位數量後的新 Date 物件。

  • 拋出錯誤:

    • Error: 如果傳入的 單位 無效，或 日期 不是有效的 Date 物件。

  • 範例:

    const 工具 = new 日期工具();
const date = new Date('2023-11-15T14:30:00Z');

// 減去 3 個月
const newDate1 = 工具.減去(date, 'month', 3);
console.log(newDate1); // 2023-08-15T14:30:00Z

// 減去 10 天
const newDate2 = 工具.減去(date, 'day', 10);
console.log(newDate2); // 2023-11-05T14:30:00Z

格式化日期(date, format)

根據指定的格式字串，將日期物件轉換為格式化的日期字串。

  • 參數:

    • date (Date): 要格式化的日期物件。

    • format (string): 指定的格式字串。

  • 返回: string - 格式化後的日期字串。

  • 拋出錯誤:

    • Error: 當 date 或 format 參數無效時。

  • 支援的格式符號:

    • YYYY: 四位數年份

    • YY: 兩位數年份

    • MM: 兩位數月份 (補0)

    • M: 月份

    • DD: 兩位數日期 (補0)

    • D: 日期

    • HH: 24小時制小時 (補0)

    • H: 24小時制小時

    • mm: 分鐘 (補0)

    • m: 分鐘

    • ss: 秒數 (補0)

    • s: 秒數

    • xxx: 毫秒 (補0)

    • DOW: 完整中文星期 (例如：星期一)

    • dow: 簡短中文星期 (例如：一)

  • 範例:

    const 工具 = new 日期工具();
const date = new Date('2023-11-01T14:30:59.123');

console.log(工具.格式化日期(date, 'YYYY-MM-DD HH:mm:ss')); // '2023-11-01 14:30:59'
console.log(工具.格式化日期(date, 'YY/M/D'));               // '23/11/1'
console.log(工具.格式化日期(date, 'DOW'));                   // '星期三'
console.log(工具.格式化日期(date, 'HH:mm:ss.xxx'));          // '14:30:59.123'

解析(dateString, format)

根據指定的格式，將日期字串解析為 Date 物件。

  • 參數:

    • dateString (string): 要解析的日期字串。

    • format (string): 日期的格式字串。

  • 返回: Date - 解析後生成的 Date 物件。

  • 拋出錯誤:

    • Error: 如果 dateString 與 format 不匹配或參數無效。

  • 支援的格式符號:

    • YYYY: 四位數年份

    • MM: 兩位數月份 (01-12)

    • DD: 兩位數日期 (01-31)

    • hh: 兩位數小時 (00-23)

    • mm: 兩位數分鐘 (00-59)

    • ss: 兩位數秒數 (00-59)

    • zzz: 三位數毫秒 (000-999)

  • 範例:

    const 工具 = new 日期工具();
const dateString = '2023-11-15 14:30:59';
const format = 'YYYY-MM-DD hh:mm:ss';
const date = 工具.解析(dateString, format);
console.log(date); // Date 物件: 2023-11-15T14:30:59.000Z

const dateString2 = '2023-11';
const format2 = 'YYYY-MM';
const date2 = 工具.解析(dateString2, format2);
console.log(date2); // Date 物件: 2023-11-01T00:00:00.000Z (日期預設為1)

在範圍內(日期, 開始, 結束)

檢查指定的日期是否在給定的日期範圍內（包含開始和結束日期）。

  • 參數:

    • 日期 (Date): 要檢查的日期。

    • 開始 (Date): 範圍的開始日期。

    • 結束 (Date): 範圍的結束日期。

  • 返回: boolean - 如果日期在範圍內，返回 true，否則返回 false。

  • 拋出錯誤:

    • Error: 如果任一參數不是有效的 Date 物件，或開始日期晚於結束日期。

  • 範例:

    const 工具 = new 日期工具();
const date = new Date(2023, 10, 15); // 2023年11月15日
const start = new Date(2023, 10, 1);  // 2023年11月1日
const end = new Date(2023, 10, 30);   // 2023年11月30日

console.log(工具.在範圍內(date, start, end)); // true

是否為有效日期字串(dateString)

檢查一個字串是否可以被成功解析為一個有效的日期。

  • 參數:

    • dateString (string): 要檢查的日期字串。

  • 返回: boolean - 如果字串是有效的日期格式，返回 true，否則返回 false。

  • 範例:

    const 工具 = new 日期工具();
console.log(工具.是否為有效日期字串('2023-11-15')); // true
console.log(工具.是否為有效日期字串('invalid-date')); // false
console.log(工具.是否為有效日期字串(12345));         // false

取得中文星期名稱(date, isShort)

取得指定日期的中文星期名稱。

  • 參數:

    • date (Date): 要取得星期名稱的日期物件。

    • isShort (boolean, 可選): 是否返回簡短格式，預設為 false。

  • 返回: string - 中文星期名稱。

  • 拋出錯誤:

    • Error: 當 date 參數不是有效的 Date 物件時。

  • 範例:

    const 工具 = new 日期工具();
const date = new Date('2023-11-01'); // 星期三
console.log(工具.取得中文星期名稱(date));      // "星期三"
console.log(工具.取得中文星期名稱(date, true)); // "三"

取得年份尾數(date)

取得指定日期物件年份的最後兩位數。

  • 參數:

    • date (Date): 要提取年份資訊的 Date 物件。

  • 返回: string - 年份的最後兩位數字串。

  • 拋出錯誤:

    • Error: 如果參數不是有效的 Date 物件。

  • 範例:

    const 工具 = new 日期工具();
const date = new Date('2023-11-15');
console.log(工具.取得年份尾數(date)); // '23'

提取(date)

從給定的日期物件中提取各個時間組件。

  • 參數:

    • date (Date): 要提取組件的 Date 物件。

  • 返回: Object - 包含年、月、日、時、分、秒、毫秒的物件。

  • 拋出錯誤:

    • Error: 如果 date 不是有效的 Date 物件。

  • 範例:

    const 工具 = new 日期工具();
const date = new Date('2023-11-15T14:30:59.123Z');
const components = 工具.提取(date);
console.log(components);
/*
{
  year: 2023,
  month: 10, // 月份從 0 開始
  day: 15,
  hour: 14,
  minute: 30,
  second: 59,
  millisecond: 123
}
*/

建構(parts)

根據提供的日期時間組件，建構一個新的 Date 物件。

  • 參數:

    • parts (Object): 包含日期時間組件的物件 (year, month, day, hour, minute, second, millisecond)。

  • 返回: Date - 根據組件建構的 Date 物件。

  • 拋出錯誤:

    • Error: 如果 parts 中缺少必要的屬性或屬性值無效。

  • 範例:

    const 工具 = new 日期工具();
const parts = {
    year: 2023,
    month: 10, // 十一月 (0 為一月)
    day: 15,
    hour: 14,
    minute: 30,
    second: 59,
    millisecond: 123
};
const date = 工具.建構(parts);
console.log(date); // 2023-11-15T14:30:59.123Z

檢查單位(單位)

內部使用方法，用於驗證給定的時間單位是否有效。

  • 參數:

    • 單位 (string): 要驗證的時間單位。

  • 拋出錯誤:

    • Error: 如果 單位 不在預定義的 Units 集合中。

  • 範例:

    const 工具 = new 日期工具();
try {
    工具.檢查單位('day'); // 不會拋出錯誤
    工具.檢查單位('hours'); // 會拋出錯誤
} catch (error) {
    console.error(error.message); // "不支援的單位"
}